package com.ccnode.codegenerator.taikaoback.service;

import java.util.Map;

/**
 * Token管理服务接口
 * 负责JWT token的生成、验证、存储和撤销等核心功能
 * 支持停车管理系统的JWT认证机制，包括单点登录控制和token黑名单管理
 *
 * @author 停车管理系统
 * @version 1.0
 */
public interface TokenService {

    /**
     * 生成访问token和刷新token
     * 为用户创建新的JWT访问token和刷新token，并存储到Redis中
     * 支持单点登录控制，确保用户在同一时间只能有一个有效的登录会话
     *
     * @param username 用户名，不能为空
     * @param userId 用户ID，不能为空
     * @return 包含token信息的Map，包括：
     *         - accessToken: 访问token
     *         - refreshToken: 刷新token
     *         - tokenType: token类型（Bearer）
     *         - expiresIn: 访问token过期时间（秒）
     *         - refreshExpiresIn: 刷新token过期时间（秒）
     * @throws RuntimeException 当token生成失败时抛出
     */
    Map<String, Object> generateTokens(String username, String userId);
























    /**
     * 验证token是否有效
     * 检查JWT token的有效性，包括：
     * 1. 检查token是否在黑名单中
     * 2. 验证JWT token本身的有效性
     * 3. 检查token是否在Redis中存在
     *
     * @param token JWT token字符串，不能为空
     * @return true表示token有效，false表示token无效
     */
    boolean validateToken(String token);

    /**
     * 刷新token
     * 使用刷新token生成新的访问token，延长用户的登录会话
     * 刷新token本身保持不变，只更新访问token
     *
     * @param refreshToken 刷新token字符串，不能为空
     * @return 包含新token信息的Map，包括：
     *         - accessToken: 新的访问token
     *         - refreshToken: 原刷新token（保持不变）
     *         - tokenType: token类型（Bearer）
     *         - expiresIn: 新访问token过期时间（秒）
     * @throws RuntimeException 当刷新token无效或刷新失败时抛出
     */
    Map<String, Object> refreshToken(String refreshToken);

    /**
     * 撤销token（登出）
     * 撤销指定用户的token，实现用户登出功能
     * 将token加入黑名单，从Redis中删除token记录，清除用户当前token
     *
     * @param token 要撤销的token字符串，不能为空
     * @param username 用户名，不能为空
     * @throws RuntimeException 当token撤销失败时抛出
     */
    void revokeToken(String token, String username);

    /**
     * 撤销用户的所有token
     * 撤销指定用户的所有有效token，强制用户下线
     * 适用于安全策略要求或管理员操作
     *
     * @param username 用户名，不能为空
     * @throws RuntimeException 当撤销操作失败时抛出
     */
    void revokeAllUserTokens(String username);

    /**
     * 获取token信息
     * 从Redis中获取token的详细信息，包括用户信息和创建时间等
     *
     * @param token JWT token字符串，不能为空
     * @return 包含token信息的Map，包括：
     *         - username: 用户名
     *         - userId: 用户ID
     *         - createTime: 创建时间戳
     *         - isRefreshToken: 是否为刷新token
     *         如果token不存在或获取失败，返回null
     */
    Map<String, Object> getTokenInfo(String token);

    /**
     * 检查用户是否已登录（是否有有效token）
     * 检查指定用户是否有有效的登录会话
     *
     * @param username 用户名，不能为空
     * @return true表示用户已登录且token有效，false表示用户未登录或token无效
     */
    boolean isUserLoggedIn(String username);

    /**
     * 强制用户下线（撤销所有token）
     * 管理员功能，强制指定用户下线并记录下线原因
     * 撤销用户的所有token，确保用户无法继续访问系统
     *
     * @param username 用户名，不能为空
     * @param reason 下线原因，用于日志记录
     * @throws RuntimeException 当强制下线操作失败时抛出
     */
    void forceUserOffline(String username, String reason);

    /**
     * 获取在线用户数量（估算）
     * 统计当前系统中有有效token的用户数量
     * 用于系统监控和统计分析
     *
     * @return 在线用户数量的估算值，如果获取失败返回0
     */
    long getOnlineUserCount();
}
